home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / cmds / kgdb.man < prev    next >
Text File  |  1990-10-18  |  4KB  |  107 lines
  1. ' Copyright 1989 Regents of the University of California
  2. ' Permission to use, copy, modify, and distribute this
  3. ' documentation for any purpose and without fee is hereby
  4. ' granted, provided that this notice appears in all copies.
  5. ' The University of California makes no representations about
  6. ' the suitability of this material for any purpose.  It is
  7. ' provided "as is" without express or implied warranty.
  8. ' 
  9. ' $Header: /sprite/src/cmds/kgdb/RCS/kgdb.man,v 1.3 90/10/18 12:21:03 kupfer Exp $ SPRITE (Berkeley)
  10. ' 
  11. .so \*(]ltmac.sprite
  12. .HS KGDB cmds
  13. .BS
  14. .SH NAME
  15. kgdb \- A kernel debugger based on GDB
  16. .SH SYNOPSIS
  17. .nf
  18. \fBkgdb\fR [\fI-mtm\fR]\ [\fIgdb options\fR] [\fIkernel\fR]
  19. .SH OPTIONS
  20. .IP "\fB\-mtm\fR" 14
  21. Invoke the debugger for the target machine given by tm.  If specified, this
  22. option must proceed all other options. The list of available target machines
  23. include sun2, sun3, sun4, and spur.
  24. .LP
  25. See the GNU GDB documentation for information about the rest of the available
  26. options.
  27. .BE
  28.  
  29. .SH DESCRIPTION
  30. .PP
  31. \fBKgdb\fR is a version of the GNU gdb debugger modified to debug Sprite
  32. kernels.
  33. This manual page only describes the parts of \fBkgdb\fR that differ 
  34. from \fBgdb\fR.  
  35. The reader is referred to the GNU GDB documentation and gdb manual page for a
  36. complete description of \fBgdb\fR.
  37. .SH "DIFFERENCES FROM GDB"
  38. .LP
  39. The "attach" and "detach" commands of \fBkgdb\fR differ from those of 
  40. \fBgdb\fR.  
  41. .IP "\fBattach\fR machine"
  42. The attach command of \fBkgdb\fR takes as an argument the hostname or 
  43. internet address of a Sprite machine to debug.  
  44. The command assumes that the specified machine is in the kernel 
  45. debugging stub and will wait for the machine to
  46. enter the debugger.  Once the connection to the machine is 
  47. established,
  48. the trap condition and any unprinted syslog messages are displayed.
  49. .IP "\fBdetach\fR [cont]"
  50. The detach command breaks the connection between \fBkgdb\fR and the
  51. currently attached machine.  If any argument is specified, the machine
  52. is continued before the connection is detached.  When used with the 
  53. "attach" command, the "detach" command allows debugging multiple machines 
  54. from the same \fBkgdb\fR session.
  55. .SH "ADDITIONS TO GDB"
  56. \fBKgdb\fR supports several commands not found in \fBgdb\fR.  The commands
  57. are:
  58. .IP "\fBpid\fR proc-id"
  59. The pid command sets the focus of the debugger on the  process whose
  60. process id is proc-id. 
  61. Once a process is choosen with the pid command,
  62. all stack reference commands such as "backtrace" and "frame" will reference
  63. this process's stack.  For example, the command "pid 0xa1139" followed
  64. by the "backtrace" command will display a stack backtrace of the process
  65. with pid of 0xa1139. Note that proc-id can be any expression supported by
  66. \fBkgdb\fR.
  67. .IP "\fBreboot\fR [string]"
  68. The reboot command reboots the current attached machine. The optional
  69. argument string is passed to the kernel routine Mach_MonReboot.  Note 
  70. that this command is the same as typing "print Mach_MonReboot(string)" followed
  71. by a break and a detach command except that the reboot command will work 
  72. even if no symbol table is loaded.
  73. .IP "\fBversion\fR"
  74. The version command prints the kernel version string of the 
  75. attached machine. This command outputs the same information as the
  76. command "print SpriteVersion()" but like the "reboot" command doesn't
  77. require a symbol table to be loaded.
  78. .IP "\fBdebug\fR hostname"
  79. The debug command is similar to the attach command differing only
  80. in the case when the specified machine is not already in the debugging stub.  
  81. Rather than waiting
  82. for the machine to enter the debugger like the attach command, the
  83. debug command will force the machine into the debugger using 
  84. the \fBkmsg\fR program. 
  85. In order for this command to work, 
  86. the \fBkmsg\fR program must be available in the current
  87. search path of \fBkgdb\fR. Because of its anti-social possiblities, 
  88. caution is urged in the use of the debug command.
  89. .SH "DELETIONS FROM GDB"
  90. .LP
  91. Several features of \fBgdb\fR are not available in \fBkgdb\fR because 
  92. they don't apply to kernel debugging.
  93. Missing features include the ability to start and kill programs with the 
  94. "run"
  95. and "kill" commands; to change the program's environment and
  96. terminal characteristics with the
  97. "set-env", "unset-env", "set-args", and "tty" commands;  
  98. and  to handle signals with
  99. "handle" and "signal" commands.  
  100. Additionaly, \fBgdb\fR's core file processing such as the 
  101. .B core
  102. command are also 
  103. not available in \fBkgdb\fR.
  104.  
  105. .SH KEYWORDS
  106. gdb, kernel, debugging, kmsg
  107.